Skip to content

Maintain versioned API docs at the website. - #273

Merged
myronmarston merged 1 commit into
mainfrom
myron/multiple-doc-versions
Mar 6, 2025
Merged

Maintain versioned API docs at the website.#273
myronmarston merged 1 commit into
mainfrom
myron/multiple-doc-versions

Conversation

@myronmarston

@myronmarston myronmarston commented Mar 6, 2025

Copy link
Copy Markdown
Collaborator

The approach I've taken is to commit an archive of each version's generated docs under config/site/archived_docs. This allows us to include all past versions of the docs in the built site without having to checkout past git commits or anything like that. And past versions of the docs work the same locally as they will when deployed.

While I don't love storing generated artifacts in source control, the archive files are relatively modest in size (under 400KB) and I can't think of a better way to make this work.

To get this working, I've used Goose to:

  • Define a new site:archive_docs[vX.Y.Z] task which depends on site:build_docs and then archives the produced docs into a new .tar.gz file.
  • Define a new site:unpack_doc_archives task which unpacks each doc archive into the appropriate directory. This has been added as a prerequisite task of site:build_docs so that it's done every time the docs get built.
  • Add the doc archives from the open source versions we've released (v0.19.0.0, v0.19.1.0, and v0.19.1.1).
  • Update the site navbar so that Docs is a dropdown that provides access to each available doc version.
  • Update the release workflow so that it archives the docs as part of cutting a release. (Unless it's a pre-release; then we skip).
  • Update gemspec metadata for each gem to link to the versioned docs instead of the main docs.

Closes #2.

Testing

See #283 for an example PR produced by a dry-run of the release workflow. It has an archive for the new version.

Here's a screenshot of the new navbar in action:

image

@CLAassistant

CLAassistant commented Mar 6, 2025

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch 2 times, most recently from b51a3d5 to 4de912a Compare March 6, 2025 15:16
@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch from 4de912a to 141443c Compare March 6, 2025 15:19
@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch from 141443c to 02eab7d Compare March 6, 2025 15:21
@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch from 02eab7d to 32697ac Compare March 6, 2025 15:23
@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch from 7fe3c05 to 17d95d5 Compare March 6, 2025 15:40
@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch from 17d95d5 to 5ddf561 Compare March 6, 2025 15:54
@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch from 5ddf561 to 5d91fdc Compare March 6, 2025 16:06
@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch from f11cfd0 to 899d56e Compare March 6, 2025 16:17
@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch from 1456fed to 3e18182 Compare March 6, 2025 16:27
@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch from 3e18182 to 361a82f Compare March 6, 2025 16:35
@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch from 361a82f to 694bfad Compare March 6, 2025 16:36
The approach I've taken is to commit an archive of each version's
generated docs under `config/site/archived_docs`. This allows us
to include all past versions of the docs in the built site without
having to checkout past git commits or anything like that. And past
versions of the docs work the same locally as they will when deployed.

While I don't love storing generated artifacts in source control, the
archive files are relatively modest in size (under 400KB) and I can't
think of a better way to make this work.

To get this working, I've used Goose to:

- Define a new `site:archive_docs[vX.Y.Z]` task which depends on `site:build_docs`
  and then archives the produced docs into a new `.tar.gz` file.
- Define a new `site:unpack_doc_archives` task which unpacks each doc archive
  into the appropriate directory. This has been added as a prerequisite task
  of `site:build_docs` so that it's done every time the docs get built.
- Add the doc archives from the open source versions we've released
  (v0.19.0.0, v0.19.1.0, and v0.19.1.1).
- Update the site navbar so that `Docs` is a dropdown that provides access
  to each available doc version.
- Update the release workflow so that it archives the docs as part of cutting
  a release. (Unless it's a pre-release; then we skip).
- Update gemspec metadata for each gem to link to the versioned docs instead
  of the `main` docs.

Closes #2.
@myronmarston
myronmarston force-pushed the myron/multiple-doc-versions branch from 303a907 to d174a36 Compare March 6, 2025 18:55

@BrianSigafoos-SQ BrianSigafoos-SQ left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@myronmarston
myronmarston enabled auto-merge March 6, 2025 19:09
@myronmarston
myronmarston merged commit 2090761 into main Mar 6, 2025
@myronmarston
myronmarston deleted the myron/multiple-doc-versions branch March 6, 2025 19:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Maintain multiple versions of the YARD docs at the website

3 participants